<body>
Implements the parser for the Dex programming language.

<h3>Design Notes</h3>

<p>Typically, parsing a computer language goes through several phases:

<ol>
<li>The input stream is broken up into lexical tokens (lexing);
<li>A well-defined grammar is applied to those tokens (parsing);
<li>A tree of high-level language constructs is created (AST generation).
</ol>

<p>Any computer science textbook will explain this to you. 
The phases of compilation are well-understood at this point,
and there are many tools available to automate most of the work involved.

<p>However, Dex has <i>special needs</i>.  Dex macros can alter the AST at will 
during compile-time, using the same parsing library as the compiler.  The parsing
library is therefore designed to make things easy for the macro writer, not 
necessarily for the compiler writer.

<p>Dex skips step #1 altogether.  A lexer is good for separating keywords from
identifiers, and for eliminating comments.  Dex has neither goal.  Comments
are first-class citizens in Dex; they are preserved in the AST because a macro
may want to examine them.  As for keywords, consider the following:

<pre>
public private = if + while - class
</pre>

<p>The above will cause a Java parser to give up, but the Dex parser considers it
a valid statement.  The statement will fail semantic analysis, but since macros
are run before semantic analysis, the statement might be transformed into something
meaningful.  Again, Dex tries to be as liberal regarding input as possible.

<p>So, Dex doesn't use a lexer.  The {@link dex.compiler.parser.Input} class does
the simple half of what a lexer would do.

<p>Dex combines steps #2 and #3 into a single step, implemented by {@link dex.compiler.Parser}.
Which was, in a decision I am sure will lead to much hilarity, written by hand.

<p>I wrote the parser by hand for three reasons.  One, compiler compilers require the
use of a lexer; see above.  Two, compiler compilers often treat the entire file as one
giant parse operation; <a href="http://www2.cs.tum.edu/projects/cup/">CUP</a> works like 
that.  CUP produces a parser with a single method, <code>parse()</code>, which produces
the entire parse tree.  It must be possible for a Dex programmer to invoke something 
like <code>parser.parseFunction()</code> to generate a specific node of a parse tree.

<p>The third and final reason is that there must exist a Dex library that parses Dex
code, because macro writers are going to need it.  That Dex library must be written by
hand because no compiler compiler can output a Dex program, and modifying existing 
compiler compilers to do so would take as much effort as writing the Dex parser.

<h3>General Notes About Dex Syntax</h3>

First and foremost, this is a moving target.  In general the syntax is derived from C.
Statements and expressions are separate concepts, however.  Expressions evaluate to a value;
statements do not.  So, for instance, <code>x = y = z</code> is impossible in Dex.
Also, <code>i++</code> and <code>++i</code> would mean the same thing in Dex, since neither
actually returns a value.  So, Dex only allows the <code>i++</code> form.

<p>I tried to eliminate extra characters wherever possible.  Statements are not terminated 
by semicolons.  Case blocks are not terminated with colons.  Control flow statements that
used to require parentheses no longer do so (although that makes the for loop look completely
alien, so I may renege on that).

<p>This is all very much a work in progress, and none of these decisions are final.  See 
the Everything.dex in the test directory for current example syntax.

<h3>Known Issues</h3>

<p>Since statements are not terminated by semicolons, the <code>return</code> statement is
now problematic.  The current approach, which I hate, is to use <code>return x</code> to
return from a function with a non-void return type, and to use <code>void</code> to 
return from a function with a void return type.  Which...ew.  But short of re-introducing
the semicolon as a necessary evil, I'm not sure what other approach to take.  <code>return(x)</code> 
and <code>return()</code> would work but...ew.

</body>
